package cn.mujiankeji.mbrowser.功能.下载.引擎

import cn.mujiankeji.mbrowser.功能.下载.模型.下载任务
import kotlinx.coroutines.flow.Flow

/**
 * 下载引擎接口
 * 定义了所有下载引擎都需要实现的标准行为。
 */
interface 下载引擎接口 {

    /**
     * 开始一个新的下载任务，或从头开始一个已存在的任务。
     * @param 任务 要下载的任务详情。
     * @return 一个 Flow，它会发射更新后的 [下载任务] 对象，反映下载进度和状态的变更。
     *         当下载完成、失败或被取消时，Flow会相应地完成或发出最终状态。
     */
    fun 开始下载(任务: 下载任务): Flow<下载任务>

    /**
     * 暂停一个正在进行的下载任务。
     * @param 任务Id 要暂停的任务的唯一标识符。
     */
    suspend fun 暂停下载(任务Id: String)

    /**
     * 取消一个下载任务。
     * 被取消的任务通常无法恢复。
     * @param 任务Id 要取消的任务的唯一标识符。
     */
    suspend fun 取消下载(任务Id: String)

    /**
     * 恢复一个之前被暂停的下载任务。
     * @param 任务 要恢复的下载任务，应包含其之前的状态和进度信息。
     * @return 一个 Flow，它会发射更新后的 [下载任务] 对象，反映下载进度和状态的变更。
     */
    fun 恢复下载(任务: 下载任务): Flow<下载任务>

    /**
     * 查询特定下载任务的当前快照状态。
     * 这提供了一个任务即时状态的视图，主要用于非响应式获取。
     * 持续的状态更新应通过 [开始下载] 或 [恢复下载] 返回的 Flow 来获取。
     * @param 任务Id 要查询的任务的唯一标识符。
     * @return 如果任务被此引擎管理且存在，则返回当前的 [下载任务] 快照；否则返回 null。
     */
    suspend fun 查询下载状态(任务Id: String): 下载任务?

} 